SearchUnit Documentation: Writing A Plug-in Event Handler

Central Event System (Plug-ins)

Writing A Plug-in Event Handler

A plug-in template project can be created from the Index Management Tool. Select the Plug-in form, enter the folder to create the project in, choose the required language and click Create Project.

For a detailed example of writing a plug-in, please see the Site Map Plug-in example. The essential aspects are;

The Plug-in Assembly

You create a DLL which contains the class "Keyoti.SearchEngine.ExternalEventHandler" and any additional classes required to perform the custom tasks. It can reference whatever other assemblies are necessary.

Class Structure

The class (ExternalEventHandler) can be written in any .NET language, but must adhere to the following requirements;

Namespace: Class must be in Keyoti.SearchEngine
Class name: ExternalEventHandler
Constructor: Must take parameters of type IEventDispatcher, and Configuration
Methods: at least 1 method called DetachHandlers with no parameters.

Following these requirements allows the search engine to use the class. The constructor should attach handlers to the events from IEventDispatcher and the DetachHandlers should detach the handlers (this is called when the EventHandlerAssemblyPath property changes).

Example

Assign Location And Content Categories

Debugging A Plug-in

By attaching the Visual Studio debugger to a running Index Management Tool, it's easy to debug a plug-in.

Start the index management tool.
From the plug-in project, attach the Visual Studio debugger to the index management tool (Debug->Attach to process)
Place a breakpoint as desired in the plug-in code.
Start indexing in the index management tool - Visual Studio should stop the process at the break point.

If the break point is marked as invalid check that the .PDB file for your plug-in DLL is in the same folder as the live plug-in DLL.

Using A Plug-in

Configuration Settings

Once you have created your assembly, you will need to setup your Search application to communicate with the new logic. To do this, set the EventHandlerAssemblyPath property in the configuration settings, to the path of your project's output DLL (the path can be either, absolute or relative to the Index Directory). The configuration file can be edited by either;

Index Management Tool: Select the Configuration or Plug-in form.
Search Admin App: Select Manage Configuration from the main window.
Programmatically: Set the Configuration. EventHandlerAssemblyPath property.
Other: The configuration.xml file can be edited directly, this is located within your Index Directory folder.

Plug-in Location & References

Any assemblies which are referenced by the plug-in assembly will need to either be in the same folder or in the GAC (the search assemblies are installed in the GAC). It is suggested that the after development, the plug-in DLL is stored in location under the Index Directory - because the Index Directory is a portable unit, locating the plug-in under it will ensure they are not separated. The EventHandlerAssemblyPath can be set relative to the Index Directory.

Log Files

To check your extension plug-in is working as expected you can view the log file CentralEventDispatcher.txt under your Index Directory, which will be updated as soon as anything is attempted using the configuration (eg. edit settings, start a tool). You will need to ensure Logging has been enabled in the configuration settings before using your plug-in.

Example of successful entry;
08/14/2008 10:51 Success, initialized external event handler assembly @ C:\Inetpub\wwwroot\Search_Extension_Plugin\bin\SearchExtensionPlugin.dll

Notes

CAS (security permission) issues:

If accessing an external assembly (ie. CustomDataSetProvider or ExternalEventHandler) in anything below Full Trust, the external assembly must be located under the application directory.

External Assembly Location Tip:

When working with a plug-in DLL and the Admin Web App., place the plug-in DLL in the application BIN directory. This will make the DLL automatically updatable, without stopping the IIS service or killing the ASP.NET worker process.
If the plug-in is outside the application and it's subdirectories, ensure the ASPNET (IIS 5) or NetworkService (IIS 6) user can access the DLL, eg. run from command prompt
cacls "path to plug-in DLL" /E /G ASPNET:R

References To Search DLLs:

It is fine to reference the search DLLs, but attention must be paid to;

The plug-in assembly may only reference the exact same assemblies as those being used by the search applications - specifically if your applications are using Keyoti.SearchEngine.Core.DLL, then the plug-in will fail if it is referencing Keyoti2.SearchEngine.Core.DLL (reason being that the identical class names will not be compatible). Note: the Search Admin web application (under Pro) uses a specific CLR version of the assemblies, which depends on what the developer has installed - therefore any plug-ins used must also reference the same CLR assemblies as the version of the admin MSI installed. For example, if the admin MSI for CLR 4 is installed, any plugin MUST reference the CLR 4 assemblies.

Like any assembly, the versions of the reference during compilation must match the version of the assembly located at run-time. Specifically, this means that when upgrading from one version of Search to another, any plug-in DLLs will need to be recompiled against the new version assemblies.